Peek Analysis Module SDK

Table of Contents

Overview

This document describes the process of creating analysis modules (formerly known as plug-ins) for EtherPeek, TokenPeek, and AiroPeek (collectively referred to as "Peek"). Analysis Modules were introduced in EtherPeek 3.0 to provide "expert" packet analysis and a flexible method of extending Peek.

Analysis modules generally fall into three categories:

1. Analysis modules that process packets and look for specific network events,
2. Analysis modules that enhance the display of information in Peek's main packet list, and
3. Analysis modules which filter packets.

Note than any analysis module can provide one or more of these features. For example, most of the analysis modules supplied with Peek perform all three functions. An analysis module controls which of these features to implement by specifying Analysis Module Properties.

Analysis modules support a simple API for extending Peek capabilities, allowing WildPackets customers to easily create custom solutions. This API has undergone several revisions since it was first introduced in EtherPeek 3.0, where the API version was 3. API versions and the products in which they are used are listed below.

Analysis modules are implemented as Dynamic Link Libraries with a message-based interface. The analysis module message dispatch routine is provided by exporting a routine with name "PlugInMain" having  the following prototype:

typedef int (WINAPI *PluginProc)( SInt16 inMessage, PluginParamBlock* ioParams ); // Win32 PluginProc

The inMessage parameter indicates the event. The ioParams parameter is a union whose contents are specific to each message. See the Messages and Their Parameters section for a description of each message and its accompanying parameters.

Peek also includes a set of exported routines, dubbed callbacks in this document, that can be utilized by analysis modules to access particular features.

Analysis module DLLs must be located in the "Plugins" subdirectory of the Peek installation directory to be loaded by Peek.

Analysis Module Properties

Attributes

Attributes are used by Peek to determine "global" properties of an analysis module. An analysis module reports its attributes to Peek during processing of the kPluginMsg_Load message. The fAttributes field of the PluginLoadParam structure is a bitfield of the flags described below.

kPluginAttr_ProcessPackets

This attribute indicates that an analysis module wants to receive kPluginMsg_ProcessPacket messages.

kPluginAttr_GetPacketString

This attribute indicates that an analysis module wants to receive kPluginMsg_GetPacketString messages. Set this attribute if the analysis module will display information in Peek's main window packet list.

kPluginAttr_HandlesSelection

This attribute indicates that an analysis module can handle kPluginMsg_Select messages. When this attribute is set, Peek will add the analysis module to a pop-up menu in the Select dialog. This allows analysis modules to provide an advanced method of post-capture filtering.

kPluginAttr_HandlesSummaries

This attribute indicates that an analysis module wants to receive kPluginMsg_Summary messages. Set this attribute if you have added support for summary statistics to your analysis module.

kPluginAttr_HasOptions

Set this attribute if your analysis module supports its own additional options. Peek uses this attribute to show an Options... button in the Analysis Module Options dialog and will send the message kPluginMsg_Options when the user clicks it.

kPluginAttr_Filters

This attribute indicates that the analysis module can handle kPluginMsg_Filter messages. When this attribute is set, Peek will add the analysis module to a pop-up menu in the dialog for editing analysis module filter nodes. This allows analysis modules to provide an advanced method of filtering.

kPluginAttr_HandlesErrorPackets

This attribute indicates that the analysis module wishes to receive error packets. When this attribute is set, Peek will send error packets (CRC, Runt, Oversize, etc.) to the analysis module. Most analysis modules should elect NOT to receive error packets. Note that Peek will only receive error packets (and thus, give error packets to an analysis module) if a NIC driver is being used which supports error capture. See the Peek manual for more information about error packet capture.

kPluginAttr_NameTableUpdates

This attribute indicates that the analysis module wishes to receive kPluginMsg_NameTableUpdate messages.

kPluginAttr_ProvidesAnalysis

This attribute indicates that an analysis module wants to receive kPluginMsg_GetPacketAnalysis messages. Set this attribute if the analysis module will display information in Peek's main window packet list.

kPluginAttr_HandlesApply

This attribute indicates that an analysis module chooses to receive kPluginMsg_Apply message.

kPluginAttr_PluginAdapter

This attribute indicates that an analysis module is able to serve as a capture adapter, providing packets to Peek.

kPluginAttr_DecodePackets

This attribute indicates that an analysis module is to be sent packet information for each packet decoded by the application.

Actions

Action flags are setup by an analysis module during handling of the kPluginMsg_Load. These flags indicate actions that the analysis module should take when it detects certain network events specific to the purpose of the analysis module. For example, the Duplicate Address Analysis Module that comes with Peek examines Physical and IP addresses for each packet and will trigger the actions indicated by the flags when an IP address appears to originate from two different nodes.

kPluginAction_Display

This action flag enables display of information in the Peek main window packet list. If this action is enabled, and the analysis module supports this action, then Peek will send the kPluginAttr_GetPacketString message when it needs to display this information.

kPluginAction_Notify

This action flag indicates that the analysis module should use the NotifyProc to trigger Notifications from within Peek when it needs to report network events.

Messages and Their Parameters

Messages are sent to an analysis module by Peek when an analysis module is loaded or unloaded, to process a packet, get a packet info string, notify of an event, or to perform some action such as show an about box. Messages are passed to the analysis modules main dispatch routine and may be accompanied by additional information in the following PluginParamBlock.

PluginParamBlock

typedef union PluginParamBlock
{
    PluginLoadParam             uLoad;             // kPluginMsg_Load
    PluginCreateContextParam    uCreateContext;    // kPluginMsg_CreateContext
    PluginDisposeContextParam   uDisposeContext;   // kPluginMsg_DisposeContext
    PluginProcessPacketParam    uProcessPacket;    // kPluginMsg_ProcessPacket
    PluginGetPacketStringParam  uGetPacketString;  // kPluginMsg_GetPacketString
    PluginApplyParam            uApply;            // kPluginMsg_Apply
    PluginSelectParam           uSelect;           // kPluginMsg_Select
    PluginResetParam            uReset;            // kPluginMsg_Reset
    PluginStartCaptureParam     uStartCapture;     // kPluginMsg_StartCapture
    PluginStopCaptureParam      uStopCapture;      // kPluginMsg_StopCapture
    PluginPacketsLoadedParam    uPacketsLoaded;    // kPluginMsg_PacketsLoaded
    PluginSummaryParam          uSummary;          // kPluginMsg_Summary
    PluginFilterParam           uFilter;           // kPluginMsg_Filter
    PluginNameTableUpdateParam  uNameTableUpdate   // kPluginMsg_NameTableUpdate
    PluginGetAdapterListParam   uAdapterList       // kPluginMsg_GetAdapterList
    PluginCreateNewAdapterParam uCreateAdapter     // kPluginMsg_CreateNewAdapter
    PluginDeleteAdapterParam    uDeleteAdapter     // kPluginMsg_DeleteAdapter
    PluginAdapterAttribsParam   uAdapterAttribs    // kPluginMsg_SetAdapterAttribs, kPluginMsg_GetAdapterAttribs
    PluginDecodePacketParam     uDecodePacket;     // kPluginMsg_DecodePacket
    PluginAdapterPropertiesParam uAdapterProperties; // kPluginMsg_AdapterProperties
} PluginParamBlock;

This union wraps together all the parameter blocks that are specific to each message.

kPluginMsg_Load

Peek sends this message to an analysis module when it is first loaded. The analysis module should return its API version, the analysis module name, attributes, supported and default actions, and supported ProtoSpecs. The analysis module should initialize whatever global data it may need on handling this message. See the description of the kPluginMsg_ReadPrefs message if you need to load preferences.

This message is accompanied by a PluginLoadParam structure.

PluginLoadParam

This structure accompanies the kPluginMsg_Load message.

typedef struct PluginLoadParam
{
    UInt32            fAPIVersion;
    TCHAR*            fSerialNumber;
    TCHAR*            fName;
    PluginID          fID;
    UInt16            fAttributes;
    UInt16            fSupportedActions;
    UInt16            fDefaultActions;
    UInt32            fSupportedCount;
    UInt32*           fSupportedProtoSpecs;
    ClientAppDataPtr  fClientAppData;
    void*             fAppContextData;
    TCHAR*            fLoadErrorMessage;
    LCID              fLocaleId;
    bool              fIsAppUnicode;
} PluginLoadParam;

kPluginMsg_Unload

Peek sends this message to an analysis module when it is unloaded. Free any additional memory and generally cleanup after the analysis module.

This message has no associated parameter structure.

kPluginMsg_CreateContext

Peek sends this message when a new context needs to be created for your analysis module. Each analysis module has one global context, one context for each open capture window, and one context for each open packet file window. This is the means by which analysis modules can, with relatively little work, support separate sets of statistics for each capture window and packet file window. Your analysis module should allocate memory for a context and return it to Peek. All subsequent context-related calls to your analysis module will include the appropriate analysis module context.

This message is accompanied by a PluginCreateContextParam structure.

PluginCreateContextParam

This structure accompanies the kPluginMsg_CreateContext message.

typedef struct PluginCreateContextParam
{
    PluginContext*         fContextPtr;
    PluginCaptureContext   fCaptureContext;
    PluginContextData      fContextData;
    PluginContextFlags     fContextFlags;
} PluginCreateContextParam;

The following values are defined for the fContextFlags field.

enum
{
    kContextType_Global        = 0x00,
    kContextType_CaptureWindow = 0x01,
    kContextType_FileWindow    = 0x02
};

kPluginMsg_DisposeContext

Peek sends this message to an analysis module when a context needs to be disposed. This happens when capture windows and packet file windows are closed. It also happens once just before the analysis module is unloaded (to dispose of the global context). Analysis modules should free the memory that was allocated in response to the kPluginMsg_CreateContext message.

This message is accompanied by a PluginDisposeContextParam structure.

PluginDisposeContextParam

This structure accompanies the kPluginMsg_DisposeContext message.

typedef struct PluginDisposeContextParam
{
    PluginContext        fContext;
} PluginDisposeContextParam;

kPluginMsg_ProcessPacket

This message is sent to an analysis module when Peek has a packet for it to process. This happens when Peek has captured a packet from the network or when a packet file is loaded.

This message will only be sent if the analysis module has set the kPluginAttr_ProcessPackets attribute during handling of the kPluginMsg_Load message, and only for packets that match one of the ProtoSpecs the analysis module requested.

Analysis modules should handle the message as quickly as possible because any delay slows overall packet processing for Peek.

This message is accompanied by a PluginProcessPacketParam structure.

PluginProcessPacketParam

This structure accompanies the kPluginMsg_ProcessPacket message.

typedef struct PluginProcessPacketParam
{
    const PluginPacket* fPacket;
    const UInt8*        fPacketData;
    UInt64              fPacketNumber;
    UInt8               fMediaType;
    UInt8               fMediaSubType;
    UInt32              fProtoSpecMatched;
    PluginContext       fContext;
} PluginProcessPacketParam;

kPluginMsg_GetPacketString

This message is sent to an analysis module when Peek needs to display information in the Summary column of the packet list. This happens when a packet comes into view in the main packet list. Peek calls each analysis module and uses the first non-empty string returned.

The message will only be passed if the analysis module has set the kPluginAttr_GetPacketString attribute during handling of the kPluginMsg_Load message, and only for packets which match one of the ProtoSpecs the analysis module requested.

Analysis modules should handle the message as quickly as possible because any delay slows display of packets.

This message is accompanied by a PluginGetPacketStringParam structure.

PluginGetPacketStringParam

This structure is accompanies both the kPluginMsg_GetPacketString and kPluginMag_GetPacketAnalysis messages.

typedef struct PluginGetPacketStringParam
{
    const PluginPacket* fPacket;
    const UInt8*        fPacketData;
    UInt64              fPacketNumber;
    UInt8               fMediaType;
    UInt8               fMediaSubType;
    UInt32              fProtoSpecMatched;
    TCHAR*              fString;
    PluginColor         fColor;
    PluginContext       fContext;
} PluginGetPacketStringParam;

kPluginMsg_Apply

This message is passed when the user selects a packet in Peek's main packet list and chooses the Apply Analysis Module command. Typically, an analysis module will perform the same tasks as during the kPluginMsg_ProcessPacket but will not increment any summary statistics.

This message will only be sent if the analysis module has enabled the kPluginAttr_HandlesApply attribute during handling of the kPluginMsg_Load message.

The message is passed in three stages, indicated by the fCommand field in the accompanying PluginApplyParam structure:

1. The analysis module initially receives the kApplyMsg_Start command. It may display a dialog and/or save additional information in the fPrivateData field of the PluginApplyParam structure. Analysis modules should return a non-zero value to cancel the operation or zero to continue.
2. Each selected packet is then sent with the kApplyMsg_Packet command. Analysis modules should return zero if the packets is used, non-zero otherwise.
3. Finally, the analysis module is sent the kApplyMsg_End command in order to clean up, including any data stored in fPrivateData.

PluginApplyParam

This structure is passed with the kPluginMsg_Apply message.

typedef struct PluginApplyParam
{
    const PluginPacket*  fPacket;
    const UInt8*         fPacketData;
    UInt64               fPacketNumber;
    UInt8                fMediaType;
    UInt8                fMediaSubType;
    UInt32               fProtoSpecMatched;
    UInt16               fCommand;
    UInt32               fPrivateData;
    PluginContext        fContext;
} PluginApplyParam;

The following values are defined for the fCommand field.

enum
{
    kApplyMsg_Start  = 1,
    kApplyMsg_End    = 2,
    kApplyMsg_Packet = 3
};

kPluginMsg_Select

This message is passed when the user chooses to use the analysis module in Peek's Select dialog.

This message will only be sent if the analysis module has enabled the kPluginAttr_HandlesSelection attribute during handling of the kPluginMsg_Load message.

The message is passed in three stages, indicated by the fCommand field in the accompanying PluginSelectParam structure:

1. The analysis module initially receives the kSelectMsg_Start command. It may display a dialog and/or save additional information in the fPrivateData field of the PluginSelectParam structure. Analysis modules should return a non-zero value to cancel the operation or zero to continue.
2. Every packet is then sent with the kSelectMsg_Packet command. Analysis modules should return zero if the packet should be selected, non-zero otherwise.
3. Finally, the analysis module is sent the kSelectMsg_End command in order to clean up, including any data stored in fPrivateData.

PluginSelectParam

This structure is passed with the kPluginMsg_Select message.

typedef struct PluginSelectParam
{
    const PluginPacket* fPacket;
    const UInt8*        fPacketData;
    UInt64              fPacketNumber;
    UInt8               fMediaType;
    UInt8               fMediaSubType;
    UInt32              fProtoSpecMatched;
    UInt16              fCommand;
    UInt32              fPrivateData;
    PluginContext       fContext;
} PluginSelectParam;

The following values are defined for the fCommand field.

enum
{
    kSelectMsg_Start  = 1,
    kSelectMsg_End    = 2,
    kSelectMsg_Packet = 3
};

kPluginMsg_Reset

This message is sent by Peek when a packet buffer is cleared. Your analysis module should clear out all accumulated statistics contained within its context.

This message is accompanied by a PluginResetParam structure.

PluginResetParam

This structure is passed with the kPluginMsg_Reset message.

typedef struct PluginResetParam
{
    PluginContext fContext;
    const TCHAR*  fPluginAdapterID;
} PluginResetParam;

kPluginMsg_StartCapture

This message is sent by Peek to notify analysis modules of when packet capture is started.

This message is accompanied by a PluginStartCaptureParam structure.

PluginStartCaptureParam

This structure is passed with the kPluginMsg_StartCapture message.

typedef struct PluginStartCaptureParam
{
    PluginContext fContext;
} PluginStartCaptureParam;

kPluginMsg_StopCapture

This message is sent by Peek to notify analysis modules of when packet capture is stopped.

This message is accompanied by a PluginStopCaptureParam structure.

PluginStopCaptureParam

This structure is passed with the kPluginMsg_StopCapture message.

typedef struct PluginStopCaptureParam
{
    PluginContext fContext;
} PluginStopCaptureParam;

kPluginMsg_PacketsLoaded

This message is sent by Peek when after a packet file has completed loading.

This message is accompanied by a PluginPacketsLoadedParam.

PluginPacketsLoadedParam

This structure is passed with the kPluginMsg_PacketsLoaded message.

typedef struct PluginPacketsLoadedParam
{
    PluginContext fContext;
} PluginPacketsLoadedParam;

kPluginMsg_About

Peek sends this message to a analysis module when the user selects the analysis module in Peek's Analysis Module dialog and clicks the About button. The analysis module should display a dialog or message box with author information, the purpose of the analysis module and instructions on its use.

This message has no accompanying parameter data structure.

kPluginMsg_Options

Peek sends this message to an analysis module when the user selects the analysis module in Peek's Analysis Module dialog and clicks the Options button. Analysis modules should display a dialog box in which the user can set preferences supported by the analysis module.

Peek will only enable the Options button if the analysis module has the kPluginAttr_HasOptions attribute.

There is no accompanying parameter data structure for this message.

kPluginMsg_ReadPrefs

Peek sends this message to an analysis module right after it's loaded (during Peek launch). The analysis module can take this opportunity to load any user preferences specific to the analysis module. Use the PrefsGetValueProc and/or PrefsGetPrefsPathProc callbacks to retrieve your preferences.

This message has no accompanying parameter data structure.

kPluginMsg_WritePrefs

Peek sends this message to an analysis module right before it's unloaded (during Peek quit). The analysis module can take this opportunity to save any user preferences specific to the analysis module. Use the PrefsSetValueProc and/or PrefsGetPrefsPathProc callbacks to store your preferences.

This message has no accompanying parameter data structure.

kPluginMsg_Summary

This message is sent by Peek when it is time to update the values in the summary statistics. If your analysis module keeps track of any values for the summary statistics, it should use the SummaryModifyEntryProc and SummaryGetEntryProc callbacks as appropriate.

The message will only be passed if the analysis module has set the kPluginAttr_HandlesSummaries attribute during handling of the kPluginMsg_Load message.

This message is accompanied by a PluginSummarParam structure.

PluginSummaryParam

This structure is passed with the kPluginMsg_Summary message.

typedef struct PluginSummaryParam
{
    PluginContext fContext;
} PluginSummaryParam;

kPluginMsg_Filter

This message is passed when a packet is being evaluated by a filter which contains an analysis module filter node. Analysis modules should evaluate the packet passed in the associated PluginFilterParam parameter and determine if the packet should be accepted or rejected. If the packet should be accepted, your analysis module should return PLUGIN_RESULT_SUCCESS. If the packet should be rejected, return a value less than 0. You may specify a slice length for the packet by setting the value of the fBytesAccepted field to the number of bytes to slice to. You can use the constant PLUGIN_ACCEPT_WHOLE_PACKET to accept the entire packet without having to specify the packet's actual length. If this packet is accepted into a buffer which also has a slice length specified, slicing will occur at the smallest slice length specified.

This message will only be passed if the analysis module has set the kPluginAttr_Filters attribute during handling of the kPluginMsg_Load message. Analysis Module Filtering is only supported in Peek for the Mac 4.0.1 or later and Peek for Windows 4.0 or later. Analysis Modules which support filtering will still work under the previous version of Peek but the filtering feature will not be accessible.

It is very important to make the handling of this message as fast as possible to avoid degrading Peek's capture performance.

This message is accompanied by a PluginFilterParam structure.

PluginFilterParam

This structure is passed with the kPluginMsg_Filter message.

typedef struct PluginFilterParam
{
    const PluginPacket* fPacket;
    const UInt8*        fPacketData;
    UInt8               fMediaType;
    UInt8               fMediaSubType;
    UInt16              fProtoSpecMatched;
    SInt16              fBytesAccepted;
    PluginContext       fContext;
} PluginFilterParam;

kPluginMsg_FilterOptions

Peek sends this message when the user is configuring an advanced filter containing an analysis module node. In response to this message, an analysis module should present a dialog box that allows the user to adjust its filtering parameters.

Similar to the kPluginMsg_Filter message, an analysis module must set the kPluginAttr_Filters attribute during handling of the kPluginMsg_Load message.

This message has no accompanying parameter data structure.

kPluginMsg_SummaryDescr

This message is not used at this time.

kPluginMsg_NameTableUpdate

This message is sent by Peek when a change is made to the Name Table. Analysis modules should update any references or caches of name table entries. There are three types of name table changes: additions, edits, and deletions. Which one is being sent is indicated by the fCommand field in the PluginNameTableUpdateParam structure.

Analysis modules only receive name table notifications if the kPluginAttr_NameTableUpdates attribute was set during the handling of the kPluginMsg_Load message.

Although the associated PluginNameTableUpdateParam structure contains the fContext field, this message is not particular to any single context, and is not sent for each context. In fact, the fContext field always references the context created while handling the kPluginMsg_CreateContext message for the global context.

PluginNameTableUpdateParam

This structure is a parameter to the kPluginMsg_NameTableUpdate message.

typedef struct PluginNameTableUpdateParam
{
    PluginContext         fContext;
    PluginNameTableEntry  fEntry;
    UInt16                fCommand;
} PluginNameTableUpdateParam

The fCommand field may contain the following values.

enum
{
    kNameTableUpdateMsg_Add,
    kNameTableUpdateMsg_Edit,
    kNameTableUpdateMsg_Delete
};

kPluginMsg_GetPacketAnalysis

This message is sent to an analysis module when Peek needs to display information in the Expert column of the packet list. This happens when a packet comes into view in the packet list. Peek calls each analysis module and uses the first non-empty string returned.

The message will only be passed if the analysis module has set the kPluginAttr_ProvidesAnalysis attribute during handling of the kPluginMsg_Load message, and only for packets which match one of the ProtoSpecs the analysis module requested.

Analysis modules should handle the message as quickly as possible because any delay slows display of packets.

The message is accompanied by a PluginGetPacketStringParam structure.

kPluginMsg_CreateNewAdapter

Peek sends this message to an analysis module to instruct the module to create a new capture adapter.  This occurs when the user double-clicks the "New Remote Adapter" item under the module in the Adapter section of the Capture Options dialog.

The message will only be passed if the analysis module has set the kPluginAttr_PluginAdapter attribute during handling of the kPluginMsg_Load message.

PluginCreateNewAdapterParam

This structure is a parameter to the kPluginMsg_CreateNewAdapter message.

typedef struct PluginCreateNewAdapterParam
{
    TCHAR* fOutSelectedAdapterTag;
    UInt16 fInMaxLength;
} PluginCreateNewAdapterParam;

kPluginMsg_GetAdapterList

Peek sends this message to an analysis module to retrieve the current list of adapters available for this capture module.

The message will only be passed if the analysis module has set the kPluginAttr_PluginAdapter attribute during handling of the kPluginMsg_Load message.

PluginGetAdapterListParam

This structure is passed with the kPluginMsg_GetAdapterList message.

typedef struct PluginGetAdapterListParam
{
    const TCHAR* fOutXMLAdapterList;
    UInt32       fOutXMLStreamLength;
} PluginGetAdapterListParam;

kPluginMsg_DeleteAdapter

Peek sends this message to an analysis module to instruct the module to delete an adapter from it's list.  This occurs when the user right-click an adapter and chooses "Delete".

The message will only be passed if the analysis module has set the kPluginAttr_PluginAdapter attribute during handling of the kPluginMsg_Load message.

PluginDeleteAdapterParam

This structure is passed with the kPluginMsg_DeleteAdapter message.

typedef struct PluginDeleteAdapterParam
{
    const TCHAR* fInDeleteID;
} PluginDeleteAdapterParam;

kPluginMsg_SetAdapterAttribs

Peek sends this message to an analysis module to instruct the module to set the attributes of one of it's adapters.

The message will only be passed if the analysis module has set the kPluginAttr_PluginAdapter attribute during handling of the kPluginMsg_Load message.

kPluginMsg_GetAdapterAttribs

Peek sends this message to an analysis module to retrieve the attributes of one of it's adapters.

The message will only be passed if the analysis module has set the kPluginAttr_PluginAdapter attribute during handling of the kPluginMsg_Load message.

PluginAdapterAttribsParam

This structure is passed with the kPluginMsg_SetAdapterAttribs and kPluginMsg_GetAdapterAttribs message.

typedef struct PluginAdapterAttribsParam
{
    const TCHAR* fAdapterID;
    const TCHAR* fInParamTagStream;
    UInt32       fInParamTagStreamLen;
    const TCHAR* fOutParamTagStream;
    UInt32       fOutParamTagStreamLen;
} PluginAdapterAttribsParam;

kPluginMsg_AdapterProperties

Peek sends this message to an analysis module to allow it to display properties for its adapters.

The message will only be passed if the analysis module has set the kPluginAttr_PluginAdapter attribute during handling of the kPluginMsg_Load message.

PluginAdapterPropertiesParam

This structure is passed with the kPluginMsg_AdapterProperties message.

typedef struct PluginAdapterPropertiesParam
{
    const TCHAR* fInAdapterID;
} PluginAdapterPropertiesParam;

kPluginMsg_DecodePacket

Peek sends this message to an analysis module to inform it that the application is about to decode a packet.

The message will only be passed if the analysis module has set the kPluginAttr_DecodePacket attribute during handling of the kPluginMsg_Load message.

PluginDecodePacketParam

This structure is passed with the kPluginMsg_DecodePacket message.

typedef struct PluginDecodePacketParam
{
    const PluginPacket* fPacket;
    const UInt8*        fPacketData;
    UInt64              fPacketNumber;
    UInt8               fMediaType;
    UInt8               fMediaSubType;
    UInt32              fProtoSpecMatched;
    PluginContext       fContext;
} PluginDecodePacketParam;

Callbacks

Peek exports a set of functions that analysis modules can use to access features of Peek, such as ProtoSpecs and the Name Table, or use as utility routines to aid in packet parsing, for example.

ProtoSpec Callbacks

Peek identifies protocols by placing them in a hierarchy in which each protocol has a unique, 16-bit unsigned identifier. You can view this hierarchy in the dialog used to set up protocol filters in Peek. However, this dialog doesn't show the integer ids that are needed in analysis modules. Click here to view a text file listing the entire ProtoSpec hierarchy with the identifiers for each protocol.

IsDescendentOfProc

int
IsDescendentOfProc(
    UInt16        inSubProtocol,
    const UInt16* inParentArray,
    SInt16        inParentCount );

Remarks

Use this callback to determine if a ProtoSpec id is a subprotocol of any of a number of possible parent ProtoSpecs. See the section ProtoSpecs for a description of ProtoSpecs.

This is the only callback which is safe to call when handling a kPluginMsg_Filter message.

Return Value

The return value is the index of the parent matched in the array or -1 if there's no match.

GetProtocolNameProc

int
GetProtocolNameProc(
    UInt16 inProtocol,
    TCHAR* outString );

Remarks

Use this callback to look up the name of a protocol based on the ProtoSpec ID.

Return Value

Returns 0 if successful, non-zero otherwise.

GetProtocolLongNameProc

int
GetProtocolLongNameProc(
    UInt16 inProtocol,
    TCHAR* outString );

Remarks

Use this callback to look up the long name of a protocol based on the ProtoSpec ID.

Return Value

Returns 0 if successful, non-zero otherwise.

GetProtocolHierNameProc

int
GetProtocolHierNameProc(
    UInt16 inProtocol,
    TCHAR* outString );

Remarks

Use this callback to look up the hierarchical name of a protocol based on the ProtoSpec ID.

Return Value

Returns 0 if successful, non-zero otherwise.

GetProtocolParentProc

int
GetProtocolParentProc(
    UInt16  inProtocol,
    UInt16* outProtocolParent );

Remarks

Use this callback to look up the parent protocol of a protocol based on the ProtoSpec ID.

Return Value

Returns 0 if successful, non-zero otherwise.

GetProtocolColorProc

int
GetProtocolColorProc(
    UInt16    inProtocol,
    COLORREF* outColor );

Remarks

Use this callback to look up the color of a protocol based on the ProtoSpec ID.

Return Value

Returns 0 if successful, non-zero otherwise.

PacketGetDataLayerProc

UInt8*
PacketGetDataLayerProc
( 
    UInt32              inProtoSpec, 
    UInt8               inMediaType, 
    UInt8               inSubType, 
    const PluginPacket* inPacket,
    const UInt8*        inPacketData, 
    UInt16*             ioBytesLeft, 
    UInt32*             outSourceProtoSpec );

Remarks

Use this callback to look up the start of the payload of the packet given a protocol ID.

Return Value

Returns a pointer in the packet data where the payload for that protocol layer starts.

PacketGetHeaderLayerProc

UInt8*
PacketGetHeaderLayerProc
( 
    UInt32              inProtoSpec, 
    UInt8               inMediaType, 
    UInt8               inSubType, 
    const PluginPacket* inPacket,
    const UInt8*        inPacketData, 
    UInt16*             ioBytesLeft, 
    UInt32*             outSourceProtoSpec );

Remarks

Use this callback to look up the start of the header of the packet given a protocol ID.

Return Value

Returns a pointer in the packet data where the header for that protocol layer starts.

Name Table Callbacks

LookupNameProc

int
LookupNameProc(
    PluginNameTableEntry* ioEntry );

Remarks

Use this callback to retrieve a name from an address in Peek's name table. The ioEntry (see PluginNameTableEntry) parameter must contain the address on which to search in the fEntry and fEntryType fields. The entry type specified in fEntryType determines how much data Peek expects to find in address specified by the fEntry field. Clients using this callback are responsible for ensuring that the fName field points to ample storage (256 characters including the terminating null character) in which to receive the name upon successful lookup as well as deallocating that storage when no longer needed.

Return Value

If the address is found in the name table, the return value is 0 and ioEntry is populated with the resulting name and other name table information. If the entry is not found in the name table, the return value is non-zero.

LookupEntryProc

int
LookupEntryProc(
    PluginNameTableEntry* ioEntry );

Remarks

Use this callback to perform a reverse lookup (from name to address) in Peek's name table. Set the fName and fEntryType fields of ioEntry (see PluginNameTableEntry) for which to search. The fEntry field must point to enough storage to contain the resulting address, which depends on the entry type.

Return Value

Returns 0 if the name is found in the name table and ioEntry is populated with the resulting address and other name table information. If the name is not found in the name table, the return value is non-zero.

AddNameEntryProc

int
AddNameEntryProc(
    const PluginNameTableEntry* ioEntry,
    UInt16                      inOptions );

Remarks

Use this callback to add an entry to Peek's name table. Pass in a completely populated name table entry in ioEntry (see PluginNameTableEntry). If the group name specified in the fGoup field doesn't exist, it will be created. Pass NULL for fGroup if you wish the entry to be at the root level of the name table.

The inOptions parameter determines the actions Peek should take when a pre-existing matching entry is found. Options flags are defined below:

// AddNameEntry callback options.
enum
{
    kSetEntryName_NoMatchAdd        = 0x0001,
    kSetEntryName_NoMatchSkip       = 0x0002,
    kSetEntryName_NameMatchAdd      = 0x0010,
    kSetEntryName_NameMatchReplace  = 0x0020,
    kSetEntryName_NameMatchSkip     = 0x0040,
    kSetEntryName_AddrMatchAdd      = 0x0100,
    kSetEntryName_AddrMatchReplace  = 0x0200,
    kSetEntryName_AddrMatchSkip     = 0x0400
};

Not all combinations are valid. Choose one from each of the following categories:

Return Value

Returns 0 if successful. Any other value indicates failure.

InvokeNameEditDialogProc

int
InvokeNameEditDialogProc(
    PluginNameTableEntry* inEntry );

Remarks

This callback is used to invoke the name edit dialog. The inEntry parameter (see PluginNameTableEntry) should be populated to the best of the client's knowledge to give the user a head start on filling in fields in the dialog. If the user chooses the OK button in the dialog, the entry is added to the name table.

Return Value

Returns 0 if the name edit dialog was successfully invoked, regardless of the user's course of action thereafter. Any other value indicates failure.

ResolveAddressProc

int
ResolveAddressProc(
    UInt8* inAddress,
    UInt16 inAddressType );

Remarks

This callback queues an attempt to resolve the given address to a name. Resolving address occurs asynchronously, so this call returns immediately. The function may be called repeatedly to queue any number of address resolutions. The Name Resolver dialog is displayed until all outstanding attempts are completed.

The inAddress and inAddressType parameters are of the same types as the fEntry and fEntryType fields found in the PluginNameTableEntry structure.

This callback was introduced after the initial release of API version 5, and is only found in Peek builds 4.6 or higher.

Return Value

Returns 0 upon successfully queuing up the resolve request. Returns non-zero otherwise.

Packet List Callbacks

SelectPacketsProc

int
SelectPacketsProc(
    PluginAppContext     inAppContext,
    PluginCaptureContext inCaptureContext,
    UInt32               inPacketCount,
    UInt64*              inPacketArray,
    UInt32               inFlags );

Remarks

Use this callback to select packets in a Capture Window. The packets to select are listed in the inPacketArray parameter.

For possible values for the inFlags parameter, see the Remarks section for the SelectPacketsExProc callback.

Return Value

Returns 0 if successful. Any other value indicates failure.

SelectPacketsExProc

int
SelectPacketsExProc(
    PluginAppContext     inAppContext,
    PluginCaptureContext inCaptureContext,
    const UInt8*         inSrcAddr,
    UInt16               inSrcAddrType,
    const UInt8*         inDestAddr,
    UInt16               inDestAddrType,
    UInt16               inSrcPort,
    UInt16               inDestPort,
    UInt16               inPortTypes,
    bool                 inBothDirections,
    UInt32               inFlags );

Remarks

Use this callback to select packets in a Capture Window. The packets to select are based on the criteria specified by the parameters.

The tables below show possible values for the inFlags member.  Note that a flag and an action should be logically OR'ed together into the flags field.  For example, specifying kSelectPacketsFlag_ReplaceSelection | kSelectPacketsAction_HideSelected will replace the current packet selection with the selection criteria you specify, and then automatically hide the selected packets.

Return Value

Returns 0 if successful, non-zero otherwise.

InsertPacketProc

int
InsertPacketProc(
    const PluginPacket* inPacket,
    const UInt8*        inPacketData,
    UInt8               inMediaType,
    UInt8               inMediaSubtype,
    UInt32              inReserved );

Remarks

Use this callback to insert a packet into the packet list.

Return Value

Returns 0 if successful, non-zero otherwise.

ClaimPacketStringProc

int
ClaimPacketStringProc(
    PluginAppContext     inAppContext,
    PluginCaptureContext inCaptureContext,
    UInt64               inPacketNumber,
    bool                 inExpert );

Remarks

This callback is used to claim a string for a particular packet based on the packet number of that packet.

Return Value

Returns 0 if successful, non-zero otherwise.

Preferences Callbacks

PrefsGetValueProc

int
PrefsGetValueProc(
    PluginAppContext     inAppContext,
    PluginCaptureContext inCaptureContext,
    const TCHAR*         inName,
    const void*          outData,
    UInt32*              ioLength );

Remarks

This callback is used to retrieve a user preference value. It should normally be called in response to a kPluginMsg_ReadPrefs message.

Return Value

Returns 0 if successful, non-zero otherwise.

PrefsSetValueProc

int
PrefsSetValueProc(
    PluginAppContext     inAppContext,
    PluginCaptureContext inCaptureContext,
    const TCHAR*         inName,
    const void*          inData,
    UInt32               inLength );

Remarks

This callback is used to store a user preference value. It should normally be called in response to a kPluginMsg_WritePrefs message.

Return Value

Returns 0 if successful, non-zero otherwise.

PrefsGetPrefsPathProc

int
PrefsGetPrefsPathProc(
    char* outString );

Remarks

This callback retrieves the registry key path of where an analysis module's preferences are stored. This callback can be used if an analysis module chooses to use its own registry accessing routines instead of the PrefsGetValueProc and PrefsSetValueProc callbacks.

This callback was introduced after the initial release of API version 5, and is only found in Peek builds 4.6 or higher.

Return Value

Returns 0 if successful, non-zero otherwise.

Summary Statistics Callbacks

SummaryModifyEntryProc

int
SummaryModifyEntryProc(
    PluginAppContext     inAppContext,
    PluginCaptureContext inCaptureContext,
    const TCHAR*         inLabel,
    const TCHAR*         inGroupName,
    UInt32               inType,
    void*                inData );

Remarks

Use this callback to add or modify a summary entry. The inType parameter should consist of various flags indicating the type, format, and whether the statistic can be charted.

The type flags are as follows:

In addition, you must specify a size for the entry. The size should be logical OR'ed with the type (eg, kPluginSummaryType_Duration | kPluginSummarySize_UInt32). The size specified must be one of the following:

There are also a series of optional flags which are used to give Peek some hints about how the data should be handled. Peek versions 4.1 and higher have the ability to graph and/or create alarms based on any summary statistic, including those created by your analysis module. In order for these features to work correctly, you may need to give Peek some hints about your data by setting these flags:

Return Value

Returns 0 if successful, non-zero otherwise.

SummaryGetEntryProc

int
SummaryGetEntryProc(
    PluginAppContext     inAppContext,
    PluginCaptureContext inCaptureContext,
    const TCHAR*         inName,
    const TCHAR*         inGroup,
    UInt32*              outType,
    void**               outData,
    UInt8*               outSource );

Remarks

Use this callback to retrieve a summary entry. For the values for outType and format of outData, see SummaryModifyEntryProc. The outSource parameter is unused, but a valid UInt8 pointer must still be supplied.

Return Value

Returns 0 if the statistic was successfully found, and outType will hold flags describing the type of data pointed to by outData. Any other value indicates failure, most likely because the statistic specified by inName cannot be found.

Packet Parsing Callbacks

PacketGetLayerProc

const UInt8*
PacketGetLayerProc(
    UInt8               inLayerType,
    UInt8               inMediaType,
    UInt8               inMediaSubtype,
    const PluginPacket* inPacket,
    const UInt8*        inPacketData,
    UInt16*             ioBytesLeft );

Remarks

This callback is used to obtain a pointer to a particular layer of a packet. The inLayerType parameter consists of flags telling Peek which portion of the packet to locate. Values must be one of the following:

In addition, you must specify a layer. The layer should be logically OR'ed with the layer type (e.g., kPacketLayerType_Header | kPacketLayer_IP). The packet layer must be one of the following:

Return Value

A pointer to the specified layer of the packet will be returned (or NULL on error), and ioBytesLeft will be set to the number of bytes remaining in the packet (counting from the returned pointer).

PacketGetAddressProc

int
PacketGetAddressProc(
    PluginAppContext     inAppContext,
    PluginCaptureContext inCaptureContext,
    UInt8                inAddressSelector,
    UInt8                inMediaType,
    UInt8                inSubType,
    const PluginPacket*  inPacket,
    const UInt8*         inPacketData,
    UInt64               inPacketNumber,
    UInt8*               outAddress,
    UInt16*              outAddressType );

Remarks

This callback will copies an address from a packet into a buffer. Which address is copied from the packet is specified by the following values for the inAddressSelector parameter.

enum
{
    kAddressType_SrcPhysical,
    kAddressType_DestPhysical,
    kAddressType_SrcLogical,
    kAddressType_DestLogical,
    kAddressType_BSSID,
    kAddressType_Receiver,
    kAddressType_Transmitter,
    kAddressType_Address1,
    kAddressType_Address2,
    kAddressType_Address3,
    kAddressType_Address4
};

Address selectors kAddressType_SrcPhysical through kAddressType_DestLogical apply to both LAN and wireless packets. The remaining address selectors apply to wireless packets only.

The outAddress parameter must point to a buffer of sufficient space to hold the address when it is copied.

This callback is particularly useful for certain wireless control packets that don't have both a destination address specified in the packet. In those cases, Peek is able to deduce the destination address by traversing the packet list backwards to look for the sender in the packet to which the control packet is replying.

This callback was introduced after the initial release of API version 5, and is only found in Peek builds 4.6 or higher.

Return Value

If the address was successfully extracted from the packet, the return value is 0 and the buffer pointed to by outAddress will contain the address and outAddressType will indicate the type of address (see PluginNameTableEntry for address types). Any other value indicates failure.

Other Callbacks

AddTabProc

int
AddTabProc(
    PluginAppContext     inAppContext,
    PluginCaptureContext inCaptureContext,
    const TCHAR*         inTabName,
    const TCHAR*         inWindowClass,
    void**               outTabWnd );

Remarks

Use this callback to add a custom tab to the Capture Window UI. The tab will be titled with the string specified in the inTabName parameter. The inWindowClass parameter specifies either the Win32 window class name (registered with the system using the RegisterClass Win32 function) or a COM class name. The window or COM object will be created by Peek and added to the Capture Window UI before returning.

Return Value

If successful the callback returns 0 and the outTabWnd parameter contains either a window handle or an interface pointer, depending on the type of class name specified in the inWindowClass parameter. All other values indicate failure.

MakeFilterProc

int
MakeFilterProc(
    const UInt8* inSrcAddr,
    UInt16       inSrcAddrType,
    const UInt8* inDestAddr,
    UInt16       inDestAddrType,
    UInt16       inSrcPort,
    UInt16       inDestPort,
    UInt16       inPortTypes,
    bool         inBothDirections );

Remarks

This callback is used to invoke the Edit Filter dialog. Many of the parameters correspond to input fields in this dialog. If a parameter is not used in the filter, zero or NULL can be used to indicate that. If the user chooses the OK button in the dialog, the filter is created (but not activated), otherwise the filter is aborted.

This callback was introduced after the initial release of API version 5, and is only found in Peek builds 4.6 or higher.

Return Value

Returns 0 if the Edit Filter dialog was successfully invoked, regardless of the user's course of action thereafter. Any other value indicates failure.

NotifyProc

int
NotifyProc(
    PluginAppContext     inAppContext,
    PluginCaptureContext inCaptureContext,
    UInt64               inTimeStamp,
    UInt8                inSeverity,
    const TCHAR*         inShortString,
    const TCHAR*         inLongString );

Remarks

Use this callback to trigger a Notification within Peek. Peek will log the message, or send a page or email, depending on the settings in the Peek's Notification dialog. inShortString is used in the log and the subject of an email, inLongString is used in the body of the email.

Return Values

Returns 0 if successful, non-zero otherwise, for example if the user has turned off notifications for the analysis module.

SendPacketProc

int
SendPacketProc(
    const UInt8* inPacketData,
    UInt16*      inPacketLength );

Remarks

Use this callback to send a packet, using the current send adapter.

Return Value

Returns 0 if successful, non-zero otherwise.

GetAppResourcePathProc

int
GetAppResourcePathProc(
    wchar_t* outAppResourcePath );

Remarks

Use this callback to retrieve the path to the language specific resource folder.

Return Value

Returns 0 if successful, non-zero otherwise.

Appendix

Data Types

Basic Types

Basic types are defined in the header file AGTypes.h. These types are used in the SDK to allow an analysis modules core functionality to be completely cross-platform compatible. The typedefs also enhance readability of code by making the size and signed/unsigned property of type apparent.

Media Types

enum {
    kPluginPacketMediaType_802_3, // Ethernet, Wireless Ethernet
    kPluginPacketMediaType_802_5  // Token Ring
};

Media Subtypes

enum {
    kPluginPacketMediaSubType_Native,     // Native media specified by the media type.
    kPluginPacketMediaSubType_802_11_b,   // Wireless LAN network using 802.11b.
    kPluginPacketMediaSubType_802_11_a,   // Wireless LAN network using 802.11a.
    kPluginPacketMediaSubType_802_11_gen, // Wireless LAN network using one or more 802.11 specifications.
};

Data Structures

PluginPacket

typedef struct PluginPacket
{
    UInt32       fProtoSpec;                /* ProtoSpec instance ID. */
    UInt16       fPacketLength;             /* Total length of packet. */
    UInt16       fSliceLength;              /* Sliced length of packet or zero. */
    UInt8        fFlags;                    /* CRC, frame, runt, ... */
    UInt8        fStatus;                   /* Slicing, ... */
    UInt64       fTimeStamp;                /* Timestamp in nanoseconds. */
    const UInt8* fMediaSpecInfoBlock;       /* Pointer to the first MediaSpecificPrivateHeader structure */
} PluginPacket;

This is the definition of a packet used during processing of the messages kPluginMsg_ProcessPacket and kPluginMsg_GetPacketString. Each field in the packet header is described below:

The following values are defined for the fFlags field:

enum
{
    kPluginPacketFlag_Control   = 0x01, // Control vs. data packet.
    kPluginPacketFlag_CRC       = 0x02, // Checksum error.
    kPluginPacketFlag_Frame     = 0x04, // Frame error.
    kPluginPacketFlag_RouteInfo = 0x08, // Has routing info (Token Ring).
    kPluginPacketFlag_Oversize  = 0x10, // Oversize error.
    kPluginPacketFlag_Runt      = 0x20, // Runt error.
    kPluginPacketFlag_Trigger   = 0x40, // Trigger packet.
    kPluginPacketFlag_SNAP      = 0x80  // SNAP packet.
};

The following values are defined for the fStatus field:

enum
{
    kPluginPacketStatus_Truncated       = 0x02,  // Truncated packet.
    kPluginPacketStatus_Encrypted       = 0x04,  // Originally encrypted (e.g., WEP).
    kPluginPacketStatus_DecryptionError = 0x08,  // Decryption error (e.g., WEP ICV).
    kPluginPacketStatus_Sliced          = 0x20,  // Sliced packet.
    kPluginPacketStatus_ShortPreamble   = 0x40   // Short preamble.
};

When not NULL, fMediaSpecInfoBlock points to a MediaSpecificPrivateHeader structure which is immediately followed by another private header containing additional media specific information about the packet. 

MediaSpecificPrivateHeader

The MediaSpecificPrivateHeader structure is defined as follows (see PacketHeaders.h in the SDK folder):

typedef struct MediaSpecificPrivateHeader
{
    UInt32 nSize; /* size of the whole information block, which is this struct the one that follows*/
    UInt32 nType; /* type identifier for the structure immediately following this one */
};

The following values are defined for the nType field:

#define kMediaSpecificHdrType_Invalid    0 /* not a valid type */
#define kMediaSpecificHdrType_Wireless   1 /* Obsolete */
#define kMediaSpecificHdrType_WirelessEx 2 /* The next header is a WirelessPrivateHeader */
#define kMediaSpecificHdrType_FullDuplex 3 /* The next header is a FullDuplexPrivateHeader */

WirelessPrivateHeader

The WirelessPrivateHeader is defined as follows (see PacketHeaders.h in the SDK folder):

typedef struct Wireless80211PrivateHeader
{
    UInt8  DataRate;        /* Data rate in 500 Kbps units. */
    UInt8  Channel;         /* 802.11 channel [1-255] */
    UInt8  SignalStrength;  /* Signal strength 0-100% */
    UInt8  NoiseStrength;   /* Noise strength 0-100% */
    SInt16 SignaldBm;       /* signal strength dBm */
    SInt16 NoisedBm;        /* Noise dBm */
};

The following values are of note for dBm measurements:

#define PEEK_NULL_DBM -32767 /* -32767 dBm is the smallest we can ever have in a SHORT */
#define PEEK_MIN_DBM -100    /* -100dBm is 0.1pW, which is about the smallest reasonable value one would expect */
#define PEEK_MAX_DBM -5      /* -5dBm is 320uW, which is about the largest reasonable value one would expect */

FullDuplexPrivateHeader

The FullDuplexPrivateHeader is defined as follows (see PacketHeaders.h in the SDK folder):

typedef struct FullDuplexPrivateHeader
{
    UInt32 Channel; /* Channel number */
};

The following values are of note for Channel:

#define PEEK_INVALID_DUPLEX_CHANNEL 0
 

PluginNameTableEntry

// Used for NameTable calls.
typedef struct PluginNameTableEntry
{
    UInt8*      fEntry;
    TCHAR*      fName;
    TCHAR*      fGroup;
    PluginColor fColor;
    UInt16      fEntryType;
    UInt8       fHostType;
} PluginNameTableEntry;

// Entry types used in the LookupName, LookupEntry, and AddNameEntry callbacks.
enum
{
    kEntryType_PhysicalAddr,  // 6-byte entry.
    kEntryType_AppleTalkAddr, // 4-byte entry (socket ignored).
    kEntryType_IPAddr,        // 4-byte entry.
    kEntryType_DECnetAddr,    // 6-byte entry.
    kEntryType_IPv6Addr,      // 16-byte entry.
    kEntryType_IPPort,        // 2-byte entry.
    kEntryType_ProtoSpec,     // 2-byte entry.
    kEntryType_NWPort,        // 2-byte entry.
    kEntryType_WirelessAddr,  // 6-byte entry.
    kEntryType_IPXAddr        // 10-byte entry.
}

// Host types for name lookup.
enum
{
    kHostType_Unknown,
    kHostType_Workstation,
    kHostType_Server,
    kHostType_Router,
    kHostType_Switch,
    kHostType_Repeater,
    kHostType_Printer,
    kHostType_AccessPoint
};

ByteCountPair

typedef struct ByteCountPair
{
    UInt64 fBytes;
    UInt64 fCount;
} ByteCountPair;

This structure is used in the summary statistics entries. See SummaryModifyEntryProc

typedef void* ClientAppDataPtr;

This type definition is used in PluginLoadParam.

ProtoSpecs

Peek identifies protocols by placing them in a hierarchy in which each item has a unique identifier. You can view this hierarchy in the dialog used to set up protocol filters in Peek. However, this dialog doesn't show the integer ids that are needed in analysis modules. Click here to view a C header file listing the entire ProtoSpec hierarchy with the protocol identifiers for each protocol.  Click here to view the ProtoSpecs readme.

XML Adapter Tags

These tags are used for the capture adapter calls which require XML data.

#define kAdapterTag_StartCaptureText			_T("StartCaptureText")
#define kAdapterTag_StopCaptureText			_T("StopCaptureText")
#define kAdapterEle_Group				_T("Group")
#define kAdapterEle_Adapter				_T("Adapter")
#define kAdapterTag_Name				_T("Name")
#define kAdapterTag_ID				_T("ID")
#define kAdapterTag_Speed				_T("LinkSpeed")
#define kAdapterTag_DefaultSpeed			_T("DefaultLinkSpeed")
#define kAdapterTag_MediaType			_T("MediaType")
#define kAdapterTag_MediaSubType			_T("MediaSubType")
#define kAdapterTag_Deletable			_T("Deletable")
#define kAdapterVal_False				_T("false")
#define kAdapterVal_True				_T("true")
#define kAdapterTag_Address				_T("Address")
#define kAdapterTag_PluginID			_T("PluginID")
#define kAdapterTag_Device				_T("Device")		
#define kAdapterTag_Properties			_T("Properties")		

These tags are used for capture adapters under AiroPeek and AiroPeek NX.

#define kAdapterTag_CurrentSetting			_T("Setting")	
#define kAdapterTag_Channel				_T("Channel")	
#define kAdapterTag_ESSID				_T("ESSID")		
#define kAdapterTag_BSSID				_T("BSSID")		
#define kAdapterTag_ChannelScan			_T("Scanning")	
#define kAdapterTag_Enabled				_T("Enabled")
#define kAdapterTag_Duration			_T("Duration")
#define kAdapterTag_WEPKeys				_T("WEP")		
#define kAdapterTag_Key				_T("Key")
#define kAdapterTag_KeyNum				_T("KeyNum")

Here's an example of an XML stream, as prepared in response to a kPluginMsg_GetAdapterList message under AiroPeek NX:

<<?xml version="1.0" encoding="UTF-8"?>
<RemotePluginSampleAdapters StartCaptureText="Start Remote Capture" StopCaptureText="Stop Remote Capture">
    <Group Name="Probe #1" Deletable="true" ID="0x00000001">
        <Adapter Name="Adapter #1 : 0" ID="0x00010000" LinkSpeed="0x00a7d8c0" Address="00:00:00:00:00" MediaType="IEEE 802.11b" MediaSubType="1" Device="Remote Sample Plugin Adapter" Properties="true"/>
        <Adapter Name="Adapter #1 : 1" ID="0x00010001" LinkSpeed="0x00a7d8c0" Address="00:00:00:00:00" MediaType="IEEE 802.11b" MediaSubType="1" Device="Remote Sample Plugin Adapter" Properties="true"/>
    </Group>
</RemotePluginSampleAdapters>

Here's an example of an XML stream, as prepared for a kPluginMsg_GetAdapterAttribs message to get Link Speed:

<?xml version="1.0" encoding="UTF-8"?>
<Adapter>
    <LinkSpeed/>
</Adapter>

Here's an example of an XML stream, as prepared for a kPluginMsg_GetAdapterAttribs message to get wireless settings under AiroPeek NX:

<?xml version="1.0" encoding="UTF-8"?>
<GetWirelessSettings>
    <Setting/>
    <Channel/>
    <ESSID/>
    <BSSID/>
    <Scanning/>
    <WEP/>
</GetWirelessSettings>

Here's an example of an XML stream, as prepared for a kPluginMsg_SetAdapterAttribs message to set wireless settings under AiroPeek NX:

<?xml version="1.0" encoding="UTF-8"?>
<SetWirelessSettings>
    <Setting>Channel</Setting>
    <Channel>2</Channel>
    <ESSID/>
    <BSSID/>
    <Scanning>
        <Channel Enabled="true" Duration="500">1</Channel>
        <Channel Enabled="true" Duration="500">2</Channel>
        <Channel Enabled="true" Duration="500">3</Channel>
        <Channel Enabled="true" Duration="500">4</Channel>
        <Channel Enabled="true" Duration="500">5</Channel>
        <Channel Enabled="true" Duration="500">6</Channel>
        <Channel Enabled="true" Duration="500">7</Channel>
        <Channel Enabled="true" Duration="500">8</Channel>
        <Channel Enabled="true" Duration="500">9</Channel>
        <Channel Enabled="true" Duration="500">10</Channel>
        <Channel Enabled="true" Duration="500">11</Channel>
        <Channel Enabled="true" Duration="500">12</Channel>
        <Channel Enabled="true" Duration="500">13</Channel>
        <Channel Enabled="true" Duration="500">14</Channel>
    </Scanning>
    <WEP Name="sample wep key">
        <Key KeyNum="1">0102030405</Key>
        <Key KeyNum="3">060708090A</Key>
    </WEP>
</SetWirelessSettings>

WildPackets, Inc.
1340 Treat Blvd., Suite 500
Walnut Creek, CA 94597 USA
925-937-3200
http://www.wildpackets.com/
sdkhelp@wildpackets.com

Copyright © 1997-2003 WildPackets, Inc.
All rights reserved.